
//Copyright 1997-2009 Syrinx Development, Inc.
//This file is part of the Syrinx Web Application Framework (SWAF).
// == BEGIN LICENSE ==
//
// Licensed under the terms of any of the following licenses at your
// choice:
//
//  - GNU General Public License Version 3 or later (the "GPL")
//    http://www.gnu.org/licenses/gpl.html
//
//  - GNU Lesser General Public License Version 3 or later (the "LGPL")
//    http://www.gnu.org/licenses/lgpl.html
//
//  - Mozilla Public License Version 1.1 or later (the "MPL")
//    http://www.mozilla.org/MPL/MPL-1.1.html
//
// == END LICENSE ==
using System;
using System.Collections;
using System.Collections.Generic;

namespace Swaf.BizObj
{
	/// <summary>
	/// The known implementations of the <i>business object</i> suite of interfaces.  When creating
	/// a data source (an object that implements the <c>IBizObjSource</c> interface, you must specify
	/// which implementation is needed via one of these enumeration values.
	/// </summary>
	public enum SourceType {XmlSource, BasicSource};

	/// <summary>
	/// Defines the interface for creating <c>IBizObjSource</c> for full collections of
	/// data or one off business objects.
	/// </summary>
	public interface IBizObjManager
	{
		/// <summary>
		/// Creates a new data source of the specified type, initializing it with the info
		/// passed into the call.  After this call the data source should be ready to use.
		/// </summary>
		/// <param name="type">The implementation of the <i>business object</i> suite of interfaces
		/// that is needed.</param>
		/// <param name="info">Initialization text used by the data source to get ready to work properly.  Each
		/// implementation of this interface will require different types of information to be created
		/// properly.</param>
		/// <returns>A newly created implmentation of <c>IBizObjSource</c> ready to use.</returns>
		IBizObjSource createSource(SourceType type, string info);
		IBizObjSource createSource(SourceType type, string info, string extraInfo);


		/// <summary>
		/// Creates an individual business object that is not conencted to a data soure.
		/// </summary>
		/// <remarks>
		/// The <c>SourceType</c> that the business object comes from is the <c>BasicSource</c>
		/// which is capable of having business objects exist without a full data source behind it.
		/// Not all implementations of <c>IBizObj</c> can be created like this, and that is why
		/// this method doesn't take a <c>SourceType</c> parameter</remarks>.
		/// <param name="type">A business object type defined from the application configuration file</param>
		/// <returns>A newly created <c>BasicSource</c> business object.</returns>
		IBizObj create(string type);

		IBizObjDefinition getDefinition(string type);

		IBizObjDefinition checkForDefinition(string type);
		IList Definitions{get;}

		/// <summary>
		/// Creates an IBizObjList based on the business object type passed into the method.
		/// The <c>SourceType</c> defaults to <c>SourceType.BasicSource</c>,  
		/// no search criteria is used to determine the business objects in the list,
		/// and no initialization text is specified.
		/// </summary>
		/// <param name="objectType">A business object type defined in the application configuration file.</param>
		/// <returns>A newly created <c>IBizObjList</c>.</returns>
		IBizObjList createList(string objectType);

		/// <summary>
		/// Creates an IBizObjList based on the <c>SourceType</c> and business object type passed into the method.
		/// No search criteria will be used to determine the business objects in the list, 
		/// and no initialization text is specified. Use this method to create an <c>IBizObjList</c>
		/// when the <c>SourceType.BasicSource</c> is not appropriate.
		/// </summary>
		/// <param name="srcType">The <c>SourceType</c> to use for the business object list.</param>
		/// <param name="objectType">A business object type defined in the application configuration file.</param>
		/// <returns>A newly created <c>IBizObjList</c>.</returns>
		IBizObjList createList(SourceType srcType, string objectType); 

		/// <summary>
		/// Creates an IBizObjList based on the specified <c>SourceType</c>, business object type,
		/// implementation-specfic search criteria, and initialization text.
		/// </summary>
		/// <param name="srcType">The <c>SourceType</c> to use for the business object list.</param>
		/// <param name="sourceInfo">Initialization text used by the data source to get ready to work properly. 
		/// An XML string that loads into a DOM if the type is SourceType.XmlSource. Can be an empty string.</param>
		/// <param name="objectType">A business object type defined in the application configuration file.</param>
		/// <param name="listInfo">Implementation-specfic search criteria that determines which business objects 
		/// should be included in the list. Can be null if no specific search criteria is necessary.</param>
		/// <returns>A newly created <c>IBizObjList</c>.</returns>
		IBizObjList createList(SourceType srcType, string sourceInfo, string objectType, string listInfo);

		/// <summary>
		/// Given a unique iterator set name, this will return a IBizObjIterator object that holds
		/// all of the iterators
		/// </summary>
		/// <param name="iteratorSetName"></param>
		/// <returns></returns>
		IBizObjIterator getIterator(string iteratorSetName);	
	}
}